home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
EnigmA Amiga Run 1996 March
/
EnigmA AMIGA RUN 05 (1996)(G.R. Edizioni)(IT)[!][issue 1996-03][Skylink CD IV].iso
/
earcd
/
comm2
/
xstat115.lha
/
XStat.doc
< prev
next >
Wrap
Text File
|
1994-06-20
|
18KB
|
561 lines
XStat V1.15 Documentation
=========================
Program and documentation are (C) Copyright 1992-94 by Jürgen Weinelt.
IMPORT StdDisclaimer; (* in short: use it at your own risk *)
XStat was carefully tested, but there's certainly plenty of room for bugs.
XStat V1.15 is Freeware, non-commercial distribution is o.k. as long as
the following conditions are met:
* Source, executable and documentation must be distributed together
(XStat.mod, XStat, XStat.data, XStat.doc, XStat.dok and Make),
and these files must be intact (you're not allowed to make changes).
You're NOT allowed to add files to the archive.
* This program may be included on PD/freeware CDs if I am allowed
to order one of those CDs at 50% off the retail price (or cheaper :).
Of course a free copy of the CD would be even nicer...
Exception: Fred Fish has UNCONDITIONAL permission to add this
program version to his library, no matter if he's distributing it
on floppy disk or on CD.
XStat requires AmigaOS V37 or later (that's 2.04 or later).
Purpose
=======
XStat extracts statistic information from the Xferstat file created
by some UUCICOs (tested with the SWB and wUUCP variant). The most
important information XStat offers to you is the phone cost for a
certain number of connects.
Installation
============
Copy the executable "XStat" to a directory in your "Path", preferably UUBIN:
There's only one more file that needs to be installed; it's called
"XStat.data", and should be copied to your UULIB: directory.
You'll have to customize (edit) XStat.data to complete the installation.
The new V1.14 output formats and associated environment variables are
documented in the file "FORMS.doc".
XStat.data
==========
XStat.data contains the phone cost on a "per host" basis, in the following
format:
XStat.data file header:
-----------------------
H XSTAT DATA
This header must be the first line of XStat.data
XStat.data comment line:
------------------------
# any comments you wish to add to XStat.data
You may add comment lines anywhere in your XStat.data file, except before
the file header.
XStat.data currency sign info:
------------------------------
S <currency sign>
Tells XStat the currency sign for your country. This line must come before
the first "N"-line. There can be only one "S"-line in your XStat.data file.
Examples:
# currency sign for the U.S.A.
S $
# currency sign for Germany
S DM
XStat.data host name info:
--------------------------
N <host name> <host name> ...
Starts a new connection cost data record. Must be followed by at least
one "C"-line. <host name> should be the name of a host you're directly
connected to, without any path or domain information.
Examples:
# my own newsfeed
N imart
# my alternate newsfeed
N cbmger
Since XStat V1.10, you can use the extended N-line syntax that allows
you to specify multiple host names in a single N-line. All those hosts
will have the same cost information.
Example:
# several hosts that have the same cost info's
N cbmger brewak forge
Since XStat V1.11, you can use several consecutive N-lines.
Example:
# several hosts that have the same cost info's
N cbmger
N brewak forge
Maximum line length of a N-line is 100 characters.
Since XStat V1.11, you can also use the reserved host name ".default.".
This cost info will be used for every connect for which the host name
cannot be found in XStat.data.
Since XStat V1.12 you can also use the reserved host name ".illegal.".
This name will be used by XStat whenever an XferStat line with empty
host name is encountered; some UUCiCos write such lines when a
connection is aborted prematurely.
XStat.data connection duration offset info:
-------------------------------------------
O <offset>
Tells XStat that the connection duration in the XferStat file is
off by <offset> seconds. You can use this to compensate for the
connection negotiation phase of the modems (which does not appear
in the XferStat connection time). The option was only tested with
positive offsets. The "O" line must come directly after the "N"
line. There can be only one "O" line per host.
Example:
N imart
O 13
C ...
Tells XStat that my modem will usually need 13 seconds to negotiate
a connection with imart.
XStat.data connection time/cost info:
-------------------------------------
C <start time> <duration> <price>
Tells XStat that between <start time> and <start time of next C-line>
a connection will cost <price> per <duration>. "C"-lines must follow
a "N"-line. <duration> must be in seconds, <price> in the currency of
your choice.
The first "C"-line must be for "SU-00:00:00"!
(see exception at LOCAL/IGNORE below)
Example:
N imart
C SU-00:00:00 120 0.23
C MO-08:00:00 60 0.23
C MO-18:00:00 120 0.23
From Sunday 0:00:00 to Monday 7:59:59, a connection between my
site and my newsfeed "imart" will cost 0.23DM/120sec.
Between Monday 8:00:00 and Monday 17:59:59, a connection between my site
and my newsfeed "imart" will cost 0.23DM/60sec.
With this short example, the connection cost for the rest of the
week (from Monday 18:00:00 to Saturday 23:59:59) would be 0.23DM/120sec.
Since Version 1.09 there's another possible C-line syntax... you
can also use "C IGNORE" to tell XStat to ignore all connections from
and to that particular host, or you can use "C LOCAL" to specify a
local connection without connection costs (only the in/out bytes
will be counted in this case). If you use "LOCAL" or "IGNORE", you
may NOT use the normal C-line syntax for that host.
"LOCAL" and "IGNORE" are mutually exclusive.
Example:
N imart
C IGNORE
will cause all connects from/to imart to be ignored.
Example:
N imart
C LOCAL
will cause all connects from/to imart to be counted with cost=0.
Since Version 1.14, you can also use a unit duration of "0" seconds,
which will instruct XStat to assume a "flat rate" for the
corresponding connections (one single "unit" will be counted for
those connections).
Example:
N imart
C SU-00:00:00 0 0.23
C MO-08:00:00 60 0.23
C MO-18:00:00 120 0.23
Connections between Sunday, 0:00 and Monday, 8:00 will cost one
single unit, no matter how long they were.
Full length example for XStat.data:
-----------------------------------
- cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut -
H XSTAT DATA
#==============================================================================
# XStat connection cost data file
#==============================================================================
#
#------------------------------------------------------------------------------
# currency sign for Germany; S must come before first N
#------------------------------------------------------------------------------
S DM
#
#------------------------------------------------------------------------------
# my own newsfeed, connection cost is 0.23/60sec (0.23/120sec night & weekend)
#------------------------------------------------------------------------------
N imart
N .illegal.
C SU-00:00:00 120 0.23
C MO-08:00:00 60 0.23
C MO-18:00:00 120 0.23
C TU-08:00:00 60 0.23
C TU-18:00:00 120 0.23
C WE-08:00:00 60 0.23
C WE-18:00:00 120 0.23
C TH-08:00:00 60 0.23
C TH-18:00:00 120 0.23
C FR-08:00:00 60 0.23
C FR-18:00:00 120 0.23
#
#------------------------------------------------------------------------------
# cbmger, brewak, forge, default:
# connection cost is 0.23/21sec (0.23/42sec night & weekend)
#------------------------------------------------------------------------------
N cbmger
N brewak forge
N .default.
C SU-00:00:00 42 0.23
C MO-08:00:00 21 0.23
C MO-18:00:00 42 0.23
C TU-08:00:00 21 0.23
C TU-18:00:00 42 0.23
C WE-08:00:00 21 0.23
C WE-18:00:00 42 0.23
C TH-08:00:00 21 0.23
C TH-18:00:00 42 0.23
C FR-08:00:00 21 0.23
C FR-18:00:00 42 0.23
#
#------------------------------------------------------------------------------
# modula, this is a local (e.g. null-modem) connection
#------------------------------------------------------------------------------
N modula
C LOCAL
#
#------------------------------------------------------------------------------
# walker, connects will be ignored
#------------------------------------------------------------------------------
N walker
C IGNORE
#
- cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut -
Usage
=====
XStat [?] [DATA name] [FILE name] [V | VERBOSE] [FD | FROMDATE date]
[TD | TODATE date] [NI | NOINCOM] [NO | NOOUTGO]
[H | HOSTNAME name] [M | MONTH shortdate] [SE | STDERR]
[P | PREVIOUS numdays] [L | LAST numdays]
Alternate description:
XStat FILE/K,DATA/K,V=VERBOSE/S,M=MONTH/K,NI=NOINCOM/S,NO=NOOUTGO/S,
Q=QUIET/S,H=HOSTNAME/K,FD=FROMDATE/K,TD=TODATE/K,SE=STDERR/S,
P=PERIOD/N,L=LAST/N
You may also use the environment variable "XSTATARGS" to specify
parameters. This is very useful if you're using XStat from the
Workbench (XStat doesn't really support Workbench, that's why
there's no icon for it).
?
-
Displays a help message.
DATA name
---------
Tells XStat to read its connection cost data from file <name>.
<name> defaults to "UULIB:XStat.data".
FILE name
---------
Tells XStat to extract the statistic information from file <name>.
<name> defaults to "UUSPOOL:XferStat".
V | VERBOSE
-----------
Enables the "verbose" mode. When on, XStat displays short statistics
for every connect found in the Xferstat file. Defaults to "off".
Specify VERBOSE to turn verbose mode on.
WARNING! The VERBOSE option will be changed drastically soon (probably
in the next release).
FD | FROMDATE date
------------------
Tells XStat to ignore connects before <date>. <date> defaults to "01-JAN-78".
You may use any valid AmigaDOS date string, including things like
"TODAY" or "YESTERDAY". XStat will add a time string of "00:00:00" internally,
you may not do this yourself. Be careful, if you're using Workbench 2.1 (which
is [ought to be] currently available to registered developers only) you'll have
to use your locale date specifications, for example "HEUTE" instead of "TODAY"
if you're using the german locale.
Please read the warnings for "PREVIOUS" and "LAST"!
TD | TODATE date
----------------
Tells XStat to ignore connects after <date>. <date> defaults to current
date/time. You may use any valid AmigaDOS date string, including things
like "TODAY" or "YESTERDAY" (with the same 2.1/locale limitations as FD).
XStat will add a time string of "23:59:59" internally, you may not do this
yourself.
Please read the warnings for "PREVIOUS" and "LAST"!
M | MONTH shortdate
-------------------
Tells XStat to ignore FD and TD, and to compute the statistics for the
specified month instead. The month must be given in the format "MMM-YY",
without specifying the day. Example: "MONTH JUN-92" will compute the stats
for June 92. MONTH is inactive as default.
Please read the warnings for "PREVIOUS" and "LAST"!
NI | NOINCOM
------------
Tells XStat to suppress evaluation of incoming calls; defaults to off.
Specify "NI" to suppress evaluation of incoming calls. Meaning of this
switch was inverted before version 1.04.
NO | NOOUTGO
------------
Tells XStat to suppress evaluation of outgoing calls; defaults to off.
Specify "NO" to suppress evaluation of outgoing calls. Meaning of this
switch was inverted before version 1.04.
Q | QUIET
---------
Tells XStat to suppress non-fatal error messages; defaults to off.
Specify QUIET to suppress non-fatal errors.
This is very handy for getting rid of those "(ignoring this one)" messages
for failed connects.
H | HOSTNAME
------------
Tells XStat to evaluate calls to host <name> only; defaults to all hosts.
Starting with V1.06, if <name> contains any valid AmigaDos pattern,
XStat will display subtotals for each host that matches these patterns.
Patterns are not case sensitive.
Example: XStat hostname (a|x)#?
will evaluate calls to all hosts that start with an "a" or "x",
and will display sub-totals for each of those hosts.
New feature in 1.15:
If the hostname is a simple string (no AmigaDOS patterns in it), then
XStat will just produce statistics for that hosts, NOT any "TOTAL"s.
SE | STDERR
-----------
Tells XStat to send all error messages to StdErr instead of StdOut.
Then you can redirect the statistic output to a file using ">File",
without redirecting the error messages to that file as well.
Redirection defaults to off; specify STDERR to enable redirecting
error messages to StdErr. StdErr is always the console window
XStat was started from. The STDERR option was tested with the
standard AmigaShell only. It *should* work with other shells, too.
P | PERIOD numdays
------------------
Display the statistics for a certain period of time; the period
is from "FROMDATE" to "FROMDATE+numdays".
WARNINGS:
(1) this overrides both "MONTH" and "TODATE"
(2) there's no sanity checking done on "numdays", you can cause
an internal overflow by specifying extremely large values
(3) you're not allowed to specify "PERIOD" and "LAST" simultaneously
(4) "numdays"=1 displays statistics for "FROMDATE" and the following day
L | LAST numdays
----------------
Display the statistics for a certain period of time; the period
is from "TODATE-numdays" to "TODATE".
WARNINGS:
(1) this overrides both "MONTH" and "FROMDATE"
(2) there's no sanity checking done on "numdays", you can cause
an internal underflow by specifying extremely large values
(3) you're not allowed to specify "PERIOD" and "LAST" simultaneously
(4) "numdays"=1 displays statistics for "TODATE" and the day before
XStat's output
==============
Example:
> (On 25-DEC-93) XStat last 30
>
> XStat 1.15
> © Copyright 1992-94 by Jürgen Weinelt
> XStat is Freeware - read the docs for details.
>
>
>
> TOTAL: Connection statistics for incoming calls.
>
[...]
>
>
>
> TOTAL: Connection statistics for outgoing calls.
>
> Transfer statistics from 25-Nov-93 18:24:07 to 25-Dez-93 18:24:07
>
> number of connects 54
> local connects 0
> ignored connects 0
>
> total online time 8112 seconds
> total phone units 98 units
> total phone cost 22.540 DM
> average online time 151 seconds/connect
> average phone units 1.815 units/connect
> average phone cost 0.417 DM/connect
>
> total gross read 10491743 bytes
> total gross send 1819008 bytes
> total net read 8347777 bytes
> total net send 106961 bytes
> average gross read 194292 bytes/connect
> average gross send 33686 bytes/connect
> average net read 154589 bytes/connect
> average net send 1981 bytes/connect
>
> average speed 1517 CPS (gross data transfer)
> fastest connect 1653 CPS (gross data transfer)
> average speed 1042 CPS (net data transfer)
> fastest connect 1366 CPS (net data transfer)
>
> average cost 1.920 DM/MB (gross data transfer)
> average cost 2.795 DM/MB (net data transfer)
Notes:
"gross" means, the figure includes the protocol overhead.
"net" means, the figure excludes the protocol overhead.
History
=======
V1.15 fixed FORMS.doc, fixed formatting bug, enhanced the "&HN" format,
added "WARN" returncode for empty statistics (no connects).
V1.14 added output formats, connection time offset, flat rate feature
V1.13 added "PREVIOUS" and "LAST", added date line to output
V1.12 added ".illegal." feature
fixed a potential bug in the XferStat parsing code
V1.11 added multiple N-line feature and ".default." host name to XStat.data
N-Line Syntax.
fixed a minor bug in the EOF handling of the Xferstat parser.
V1.10 added multiple name feature to XStat.data N-Line syntax
fixed a small bug in the NI/NO feature
V1.09 added LOCAL and IGNORE to XStat.data C-line syntax
V1.08 added STDERR option, replaced "ø" with "av."
V1.07 list of connection statistics was not sorted correctly. Fixed.
V1.06 extended "hostname" to include pattern matching and "per host" feature
V1.05 added "per host" statistics
V1.04 fixed a bug (problem with locale), switched to dos.library "ReadArgs()"
V1.03 added monthly statistics.
V1.02 added peak brutto/netto cps rating.
V1.01 XStat used to guru when brutto or netto xfer was 0 bytes. Fixed.
V1.00 initial release.
V0.9x several test/beta versions, limited circulation
Known problems/bugs
===================
The MONTH option yields inaccurate results. This is not a bug in XStat.
The date conversion routines from dos.library are broken; C= will fix this
in the release version of [whatever comes after Kickstart 3.0].
The online time is not very accurate. That's because the connection start
time seems to state the time the modem says "CONNECT", not the real
start time of the (phone line) connection. This can be improved by using
the new 1.14 "connection time offset" feature.
If you have questions or bug reports...
=======================================
You can contact me by eMail:
jow@rz.uni-wuerzburg.de (preferred)
jow@hcast.franken.de
jow@hcast.adsp.sub.org (avoid if possible)
Or through the snail mail:
Jürgen Weinelt
Franz-Ludwig-Strasse 10
D-97072 Wuerzburg
Germany
You might also try posting to alt.sys.amiga.uucp.
Thanks
======
The following people contributed suggestions and bug reports:
Christian Balzer
Kai Bolay
Christof Damian
Hartmut "Essich" Goebel
Tommy V. Hansen
Tapio Heiskanen
Michael-Wolfgang Hohmann
Alfredo Jahn V
Andrew "Charly" Kopp
Erik Kunze
Matthias "Tron" Scheler
Henning "Barnard" Schmiedehausen
Kai "wusel" Siering
Peter "Peti" Simons
Thank you all.